---
name: "pg_autoctl show file"
section: "1"
platform: "linux"
package: "pg-auto-failover-cli"
version: "2.2-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/pg_autoctl show file"
---

# pg\_autoctl show file(1)

pg\_autoctl show file pg\_autoctl show file - List pg\_autoctl internal files (config, state, pid)

## NAME

pg\_autoctl show file - pg\_autoctl show file

pg\_autoctl show file - List pg\_autoctl internal files (config, state, pid)

## SYNOPSIS

This command the files that **pg\_autoctl** uses internally for its own configuration, state, and pid:

```
usage: pg_autoctl show file  [ --pgdata --all --config | --state | --init | --pid --contents ]
--pgdata      path to data directory
--all         show all pg_autoctl files
--config      show pg_autoctl configuration file
--state       show pg_autoctl state file
--init        show pg_autoctl initialisation state file
--pid         show pg_autoctl PID file
--contents    show selected file contents
--json        output data in the JSON format
```

## DESCRIPTION

The **pg\_autoctl** command follows the *XDG Base Directory Specification* and places its internal and configuration files by default in places such as **~/.config/pg\_autoctl** and **~/.local/share/pg\_autoctl**.

It is possible to change the default XDG locations by using the environment variables **XDG\_CONFIG\_HOME**, **XDG\_DATA\_HOME**, and **XDG\_RUNTIME\_DIR**.

Also, **pg\_config** uses sub-directories that are specific to a given **PGDATA**, making it possible to run several Postgres nodes on the same machine, which is very practical for testing and development purposes, though not advised for production setups.

### Configuration File

The **pg\_autoctl** configuration file for an instance serving the data directory at **/data/pgsql** is found at **~/.config/pg\_autoctl/data/pgsql/pg\_autoctl.cfg**, written in the INI format.

It is possible to get the location of the configuration file by using the command **pg\_autoctl show file --config --pgdata /data/pgsql** and to output its content by using the command **pg\_autoctl show** **file --config --contents --pgdata /data/pgsql**.

See also *pg\_autoctl config get* and *pg\_autoctl config set*.

### State File

The **pg\_autoctl** state file for an instance serving the data directory at **/data/pgsql** is found at **~/.local/share/pg\_autoctl/data/pgsql/pg\_autoctl.state**, written in a specific binary format.

This file is not intended to be written by anything else than **pg\_autoctl** itself. In case of state corruption, see the trouble shooting section of the documentation.

It is possible to get the location of the state file by using the command **pg\_autoctl show file --state --pgdata /data/pgsql** and to output its content by using the command **pg\_autoctl show** **file --state --contents --pgdata /data/pgsql**.

### Init State File

The **pg\_autoctl** init state file for an instance serving the data directory at **/data/pgsql** is found at **~/.local/share/pg\_autoctl/data/pgsql/pg\_autoctl.init**, written in a specific binary format.

This file is not intended to be written by anything else than **pg\_autoctl** itself. In case of state corruption, see the trouble shooting section of the documentation.

This initialization state file only exists during the initialization of a pg\_auto\_failover node. In normal operations, this file does not exist.

It is possible to get the location of the state file by using the command **pg\_autoctl show file --init --pgdata /data/pgsql** and to output its content by using the command **pg\_autoctl show** **file --init --contents --pgdata /data/pgsql**.

### PID File

The **pg\_autoctl** PID file for an instance serving the data directory at **/data/pgsql** is found at **/tmp/pg\_autoctl/data/pgsql/pg\_autoctl.pid**, written in a specific text format.

The PID file is located in a temporary directory by default, or in the **XDG\_RUNTIME\_DIR** directory when this is setup.

## OPTIONS

- **--pgdata**

  Location of the Postgres node being managed locally. Defaults to the environment variable **PGDATA**. Use **--monitor** to connect to a monitor from anywhere, rather than the monitor URI used by a local Postgres node managed with **pg\_autoctl**.

- **--all**

  List all the files that belong to this *pg\_autoctl* node.

- **--config**

  Show only the configuration file.

- **--state**

  Show only the state file.

- **--init**

  Show only the init state file, which only exists while the command **pg\_autoctl create postgres** or the command **pg\_autoctl create** **monitor** is running, or when than command failed (and can then be retried).

- **--pid**

  Show only the pid file.

- **--contents**

  When one of the options to show a specific file is in use, then **--contents** shows the contents of the selected file instead of showing its absolute file path.

- **--json**

  Output JSON formatted data.

## ENVIRONMENT

PGDATA

Postgres directory location. Can be used instead of the **--pgdata** option.

PG\_AUTOCTL\_MONITOR

Postgres URI to connect to the monitor node, can be used instead of the **--monitor** option.

XDG\_CONFIG\_HOME

The pg\_autoctl command stores its configuration files in the standard place XDG\_CONFIG\_HOME. See the *XDG Base Directory Specification*.

XDG\_DATA\_HOME

The pg\_autoctl command stores its internal states files in the standard place XDG\_DATA\_HOME, which defaults to **~/.local/share**. See the *XDG* *Base Directory Specification*.

## EXAMPLES

The following examples are taken from a QA environment that has been prepared thanks to the **make cluster** command made available to the pg\_auto\_failover contributors. As a result, the XDG environment variables have been tweaked to obtain a self-contained test:

```
$  tmux show-env | grep XDG
XDG_CONFIG_HOME=/Users/dim/dev/MS/pg_auto_failover/tmux/config
XDG_DATA_HOME=/Users/dim/dev/MS/pg_auto_failover/tmux/share
XDG_RUNTIME_DIR=/Users/dim/dev/MS/pg_auto_failover/tmux/run
```

Within that self-contained test location, we can see the following examples.

```
$ pg_autoctl show file --pgdata ./node1
   File | Path
--------+----------------
 Config | /Users/dim/dev/MS/pg_auto_failover/tmux/config/pg_autoctl/Users/dim/dev/MS/pg_auto_failover/tmux/node1/pg_autoctl.cfg
  State | /Users/dim/dev/MS/pg_auto_failover/tmux/share/pg_autoctl/Users/dim/dev/MS/pg_auto_failover/tmux/node1/pg_autoctl.state
   Init | /Users/dim/dev/MS/pg_auto_failover/tmux/share/pg_autoctl/Users/dim/dev/MS/pg_auto_failover/tmux/node1/pg_autoctl.init
    Pid | /Users/dim/dev/MS/pg_auto_failover/tmux/run/pg_autoctl/Users/dim/dev/MS/pg_auto_failover/tmux/node1/pg_autoctl.pid
   'ANY 1 (pgautofailover_standby_2, pgautofailover_standby_3)'
$ pg_autoctl show file --pgdata node1 --state
/Users/dim/dev/MS/pg_auto_failover/tmux/share/pg_autoctl/Users/dim/dev/MS/pg_auto_failover/tmux/node1/pg_autoctl.state
$ pg_autoctl show file --pgdata node1 --state --contents
Current Role:             primary
Assigned Role:            primary
Last Monitor Contact:     Thu Mar 18 17:32:25 2021
Last Secondary Contact:   0
pg_autoctl state version: 1
group:                    0
node id:                  1
nodes version:            0
PostgreSQL Version:       1201
PostgreSQL CatVersion:    201909212
PostgreSQL System Id:     6940955496243696337
pg_autoctl show file --pgdata node1 --config --contents --json | jq .pg_autoctl
{
  "role": "keeper",
  "monitor": "postgres://autoctl_node@localhost:5500/pg_auto_failover?sslmode=prefer",
  "formation": "default",
  "group": 0,
  "name": "node1",
  "hostname": "localhost",
  "nodekind": "standalone"
}
```

## AUTHOR

Microsoft

## COPYRIGHT

Copyright (c) Microsoft Corporation. All rights reserved.